iT邦幫忙

2026 iThome 鐵人賽

DAY 26
0

半夜排查一個 production 502,跟 Claude Code 來回討論了半小時:症狀、猜測的原因、試過的修法、最後確認的根因、修好之後想到的預防措施。隔天早上想把這段過程留下來,翻開對話紀錄——找得到,但沒人會真的往上翻半小時的對話去重建一次事故的來龍去脈。下次遇到類似症狀,最後還是重新排查一次。

Day17 的 /new-adr 已經證明「把對話脈絡直接轉成結構化筆記」這個模式可行:不需要使用者先手寫草稿,Agent 直接回顧對話、整理成固定結構、寫入 vault。今天要做的 /new-postmortem 表面上是同一個模式的另一個應用,但套上去之後馬上會撞到一個 ADR 沒有的問題:ADR 記錄的是「已經拍板的決策」,/new-adr 沒有中間態,只有「討論過」跟「沒討論過」兩種區塊;postmortem 記錄的是「正在排查或剛排查完的事故」,症狀通常最先確定,根本原因可能還在假設階段,修復方式可能還在驗證中——四個資訊區塊在呼叫指令的當下,很可能處於四種不同的完整度。如果照搬 ADR 的規則,要嘛逼使用者查完全部才能建立,要嘛用同一套「待補充」含糊帶過所有不完整的情況,兩者都會丟失 postmortem 最有價值的那個時刻:症狀剛出現、細節還沒被遺忘的當下。

30_Resourcesstatus: growing 不衝突,是兩個維度

先處理一個容易搞混的地方。PARA 分類判斷問題 3 說「被動查閱的參考資料,不需要主動維護」——postmortem 寫定之後主要用途就是「下次遇到類似症狀時搜尋查閱」,不是持續編輯的日誌,跟 Day17 判斷 ADR 該進 30_Resources 的邏輯完全一樣,所以 /new-postmortem 一樣直接跳過 00_Inbox,固定寫入 vault/30_Resources/

但這裡看起來會跟接下來要講的「status 可能是 growing」互相打架——growing 不是通常代表「還在成長、需要主動維護」嗎?其實 note-metadata-schema(Day04)定義的 status 講的是筆記內容本身的成熟度,跟 PARA 資料夾分類講的這個知識領域要不要主動維護是兩個正交的維度。一篇筆記完全可以身在 30_Resources 這個「被動查閱」的資料夾,同時 status 還是 growing——因為根本原因還沒確認,內容還沒成熟——這兩件事不矛盾。這個組合在 Day04 定義受控詞彙的時候就已經合法,只是一直沒有指令真的用到,/new-postmortem 是第一個。

status 依排查完整度動態判斷,不像 ADR 寫死

ADR 的 status 固定是 evergreen,因為決策在被建立的那一刻就已經是定案的最終狀態。Postmortem 不能照搬這個假設,規則改成動態判斷:

  • 根本原因已確認 且 修復方式已套用status: evergreen(事故已完整收尾,內容視為穩定)
  • 根本原因或修復方式任一尚未確認(還在調查或驗證中)→ status: growing(允許之後回頭更新同一篇筆記)

考慮過比照 ADR 直接寫死 evergreen,把「沒查完就不准建立」當前提,後來放棄了:Bug 排查往往分階段進行,症狀剛出現時就想先留一份記錄,避免對話結束後細節被遺忘;如果強制要求查完才能建立,使用者大概率會選擇不呼叫這個指令,退回「排查完才回頭手動補記錄」的舊模式——而那正是這個指令想解決的問題。

「待確認」跟「待補充」,語意不一樣

四個區塊裡,只有 ## 問題症狀 是建立前提:完全沒有症狀討論,指令直接中止,不產生空殼筆記,跟 /new-adr 遇到「完全沒有決策脈絡」時的處理一致。其餘三個區塊,資訊不足時用了兩種不同的標記,刻意不是同一個詞:

  • ## 根本原因## 修復方式:資訊不足時標「待確認」——強調「有假設或正在進行的動作,但還沒定案/驗證完成」,這個標記會影響上一節的 status 判斷。
  • ## 預防與經驗:資訊不足時標「待補充」(沿用 /new-adr 的字眼)——這裡是單純「還沒討論過」,就算事故已經完整收尾(status: evergreen),預防措施也可能還沒想清楚,這個標記不影響 status

兩個標記都遵守跟 ADR 一樣的硬規則:不可以用聽起來合理但沒討論過的內容去填滿標記的區塊。

自動織入雙向連結:一樣是沿用,不重新設計

/new-postmortem 產生的筆記一樣有 tags 欄位,沒有理由讓它繞過 Day16 已經驗證過的自動織入邏輯,也沿用 Day15/16/17 建立前 brain scan 查同名衝突、建立後 brain health 驗證的模式——這幾件事跟 postmortem 記錄的是事故還是決策無關,屬於任何寫入 vault 的動作都該有的把關機制。

實際跑三次:收尾、排查中、預防待補

在 demo repo 的對話裡討論一個完整排查完的 CI 效能問題——brain scan 在超過 500 篇筆記的大型 vault 上偶發逾時,根本原因是逐檔查詢系統呼叫次數過多疊加 CI 磁碟 I/O 較慢,修復是改成單次目錄遍歷並調高逾時門檻,還討論了之後要補 benchmark 迴歸測試——呼叫 /new-postmortem brain scan 大型 vault 執行逾時

  1. 四個區塊都對應到實際討論內容,沒有標記。
  2. ## 根本原因## 修復方式 皆無「待確認」→ status: evergreen
  3. tags: ["golang", "cli"] 跟既有的三篇 Cobra 筆記、一篇 brain graph 筆記共享 tag,五篇筆記的 ## Related 互相補上了 Wikilink。
  4. brain health:0 筆新增斷鏈,新筆記不是孤立筆記。

再對照一個刻意只排查到一半的情境:只討論了「排程似乎重複觸發 brain health」這個症狀,根本原因只是懷疑、沒有證據確認,修復方式也還沒討論。呼叫 /new-postmortem 背景排程重複觸發健康檢查 之後,## 根本原因## 修復方式 都標「待確認」,status 正確落在 growing;因為對話裡沒有可歸類的關鍵字,tags 是空陣列,指令按規則跳過自動織入,brain health 的孤立筆記數如預期加一——這不是錯誤,只是這篇筆記目前真的沒有可以連結的對象。

第三次驗證「待確認」跟「待補充」不會互相干擾:討論完一個權限設定問題的症狀、根本原因、修復方式(三者皆已確認),但沒聊到預防措施。## 預防與經驗 標「待補充」,但因為前兩個關鍵區塊都已確認,status 依然判斷為 evergreen——證實了預防措施的缺席不會拖累事故收尾的判斷。另外對已存在同名檔案的標題重複呼叫,brain scan 偵測到衝突,中止建立,沒有覆寫既有內容;完全沒有相關討論的標題呼叫指令,也如預期直接中止並要求先說明症狀。

銜接後續

Day26 把「排查中」這個 ADR 不會遇到的中間態,用 status 動態判斷跟兩種不同語意的標記接住了,讓 Bug 排查日誌從對話視窗一關就消失的東西,變成一篇可以搜尋、可以之後回頭補齊的個人資產。Day27 進入 Stage 5 的下一步,會把這一週新增的 postmortem 跟其他筆記彙整成週報,status: growing 的 postmortem 也會是週報裡「還有事情待確認」的候選清單來源之一。


上一篇
【階段成果展】打開視覺化圖譜:呈現整理前後的知識網格對比
下一篇
研發實戰:結合 Git Commit 與 PR,自動生成週報與技術脈絡
系列文
打造 AI Agent 驅動的第二大腦:用 Go + Claude Code + Obsidian + Graphify 打造工程師知識作業系統28
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言